[原來後端要知道] 如何寫 API 文件？ #Apiary #API Blueprint # Markdown

backend 原來後端要知道 apiary api document w3hexschool 鼠年全馬鐵人挑戰

Sam 2020-04-08 21:54:14 ‧ 32078 瀏覽

分享至

攝影師：Edward Jenner，連結：Pexels

哈囉，我們又見面了，最近肺炎疫情嚴重，大家盡量還是待在家裡，不要幫助疫情增長了～寫程式有個優點就是可以遠端工作，而遠端工作時，如何有效 溝通 就特別重要了，今天要跟大家分享我身為後端，在和前端人員合作的時候，所遇到的溝通問題和怎麼透過 API 文件解決，那我們就開始囉～

前情提要

事情是這樣子的，我在做一個留言板專案，一開始純粹只用文字來切分版面，後來覺得太醜了，看下圖你就知道有多醜，

所以就改抓 bootstrap 的樣板，但是要把資料呈現到樣板上，還是蠻麻煩的，首先要先把樣板改成我想要的樣子，會遇到很多 css 和 js 的問題，真 D 麻煩，再來，還要處理頁面顯示資料的邏輯，一開始我用 Django 的 Template Engine 寫了一些 {% if xxx == yyy %}、{% for xxx in yyy %} 之類的邏輯，覺得「可惡，套用樣板之後，讓呈現畫面不醜，但是換成程式碼醜 QQ」

就當我邊寫後端邏輯、邊改前端資料邏輯的時候，我就覺得不行，我看還是找個網頁前端的人來幫我做好了，順便累積一點前後端合作的經驗，我就這樣開始了專職後端的生活，然後順便做起了這個小專案的 PM (Project Manager)，然後就是跳坑的開始 XD，下次把這過程寫成文章，再來改這篇，總之，要告訴前端：「我開的 API 是這樣的規格哦」，就需要條例式、有格式的寫清楚我開出來的規格，這樣前端才有依據來照著接 API 的資料。

1. 為什麼需要寫 `API 文件`？

一個人開發時，通常都是想到什麼做什麼，但如果有另一個人加入一起開發的話，就需要把你想的東西「文件化」，除非那個人就是你自己，不然就算你講得再清楚，都還是有可能會漏掉一些沒講的。

每個人的認知程度不一樣，尤其是在軟體開發中，因為軟體開發的範疇太廣、變化又太快，在多人協作的時候，很常會發生你以為你講清楚了，可是聽的人卻覺得很問號。

在前後端分離的概念中，後端開出 API 給前端對接，將業務邏輯的資料串起來，那麼前端要怎麼知道要對哪支 API 送什麼參數、傳什麼資料呢？

1.1 最簡單的方式

就是直接用講的，可是用講的容易忘記，而且講錯了也沒有證據（如果你是故意要挖坑給人跳的話，這倒是個好方法，阿要記得不要被錄音囉 XD）

1.2 第二直覺的方式

就是透過通訊軟體的文字，這種方法通常都是想什麼打什麼，也沒有固定格式，但如果雙方是很熟的合作對象、而且團隊就很小很小，這種方法或許還可以運作下去，反正出錯了就直接罵一罵對方，然後再改就好了；還有一個缺點，就是 沒有辦法管理 API 的版本，容易散落在各種聊天室的聊天記錄裡。

1.3 當團隊越來越大，只靠用講的已經無法讓每個人都知道目前的 API 版本時

現在最主流的方法，就是寫 API 文件 (API doc)，作為給前端對接 API 的依據，條列式、照著大家都認同的規範去寫 API 的規格，這樣就不會錯（除非有人眼殘或寫程式寫到ㄎㄧㄤ掉 XD）。

雖然我這次的專案只有我和前端，總共才兩個人

可是為什麼還是要寫 `API 文件` 呢？

因為之後我有可能要面對多個前端，勢必需要有點寫文件的經驗，先練起來放。

2. 那麼要怎麼開始寫 API 文件呢？

有很多種寫 API 文件的方法，但比起方法和工具，知道要傳達給看文件的人 什麼內容 才是最重要的，內容不外乎是包含 API 的 url、這支 API 的作用、使用的 HTTP method、header 欄位、request body、response body 等等資訊，但新手不一定知道這些，對於新手來講，這時候工具的價值才體現出來，因為工具可以幫你檢查 API 文件中該有資訊，還可以幫你排版，產出漂漂亮亮的文件檔

跟大家推薦一個線上工具：Apiary

3. 什麼是 Apiary？

先給大家看結果圖，用 Apiary 可以產出這樣的 API 文件，是不是簡潔漂亮又能清楚傳達 API 的規格呢 ~

Apiary 是一個寫 API 文件 的線上網站，採用一種名為 API Blueprint 的 API 文件語法，簡單來說，API Blueprint 利用 Markdown 語法，目的是要用來撰寫 API 文件。

等等，怎麼覺得有點饒舌，既然都是語法，那麼到底有什麼不同！？沒關係，我畫了一張圖來表示他們的關係（因為我第一次看到 API Blueprint 和 Apiary 這兩個名詞，也覺得很莫名其妙 XD）

先一層一層來了解這幾個莫名其妙的名詞的關係吧，首先 Markdown 是現在(2020年)一種廣泛被用來作為寫筆記的一種語法，用 Markdown 可以產生和 HTML 類似的元件，幾乎都找得到相對應的元件

第二，而 API Blueprint 是一種寫 API 文件 的語法，特色是利用了現在常見的 Markdown 語法作為基礎，如果不想使用 Markdown 來寫 API 文件 的話，可以使用 Swagger，這個 Swagger 是使用 YAML 語法寫的，因為 API Blueprint(使用 Markdown) 和 Swagger(使用 YAML) 的出現，可以供偏好不同語法的人都可以寫出 API 文件。

第三，最後 Apiary 是一種能視覺化 API Blueprint 語法的線上工具，除了 Apiary 可以視覺化 API Blueprint 語法之外，還有其他種工具能做到，這邊先推薦大家使用 Apiary ~

4. 怎麼使用 `Apiary` ?

因為文章已經越寫越長了，就直接引用 U 質文章囉，可以參考這篇設計API時好用的工具 - 讓前後端溝通格式不再卡卡 - 工具使用介紹篇，簡單來說，如果你已經是習慣 markdown 語法的人，那麼來上手 Apiary 就很快；如果你習慣寫 YAML 語法，那你就挑 Swagger 來寫，至於用哪一種工具都沒關係，反正目的都是一樣的：「讓前後端、團隊溝通順利，大家知道的 API 是一樣的 API」。